Skip to content

doc: note that FreeEnvironment() must not run inside uv_run() - #67660

Open
magurotuna wants to merge 1 commit into
nodejs:mainfrom
magurotuna:doc-freeenvironment-uv-run
Open

magurotuna wants to merge 1 commit into
nodejs:mainfrom
magurotuna:doc-freeenvironment-uv-run

Conversation

@magurotuna

Copy link
Copy Markdown

FreeEnvironment() runs the event loop because CleanupHandles() calls uv_run(). libuv states that uv_run() must not be called from a callback. The embedding docs do not mention this rule for FreeEnvironment(). This PR adds a warning to doc/api/embedding.md and src/node.h. The new paragraph in doc/api/embedding.md tells embedders to call FreeEnvironment() after the loop stops.

Calling FreeEnvironment() from a loop callback can hang. This repro shows the hang on Linux, macOS, and Windows with Node.js 24, 26, and the 2026-11-19 nightly (CI run). In the repro, two fs.stat() calls finish together: one in the main Environment and one in a second Environment. The libuv loop takes both finished requests at once and then runs their callbacks one by one. The first callback calls FreeEnvironment() on the second Environment. FreeEnvironment() waits for the second fs.stat() request, but the loop already took that request. The loop can run the second callback only after FreeEnvironment() returns, so the wait never ends.

Question: freeing an Environment from an addon

The updated docs tell embedders to call FreeEnvironment() after the loop stops. However, addon code usually runs inside a loop callback, for example when JavaScript calls it. How should an addon free an Environment?

My workaround in magurotuna/vitest-pool-fastforks#14 makes uv_run() return early with uv_stop() and frees the Environment in a platform task:

// Called from JavaScript, so inside uv_run().
void FreeLater(node::Environment* env) {
  pending.push_back(env);
  uv_idle_start(&idle, [](uv_idle_t*) {});  // Keep the poll phase from blocking.
  uv_check_start(&check, OnCheck);
}

// Runs in the check phase of the same loop iteration.
void OnCheck(uv_check_t* handle) {
  uv_idle_stop(&idle);
  uv_check_stop(handle);
  uv_stop(handle->loop);  // uv_run() returns after this iteration.
  runner->PostTask(std::make_unique<FreeTask>());  // Calls FreeEnvironment().
}

SpinEventLoop() runs platform tasks (DrainTasks()) after uv_run() returns, so FreeTask runs outside uv_run(). The full code is freeLater() in the repro. Its deferred mode does not hang on any CI job. Can embedders rely on this order?

Refs: #65691


AI disclosure: I used Claude Code to research and to help write the added doc and PR body. I reviewed all of them.

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. labels Nov 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Welcome to Node.js, and thank you for your first contribution!

Before review, please take a moment to read:

Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal.

FreeEnvironment() runs the event loop of the Environment. If an
embedder calls it from a callback of that loop, uv_run() runs nested,
and libuv does not allow that. It can hang: the outer uv_run() can hold
thread pool completions that the inner uv_run() never sees.

Signed-off-by: Yusuke "YT" Tanaka <ytanaka@cloudflare.com>
@magurotuna
magurotuna force-pushed the doc-freeenvironment-uv-run branch from 1779848 to ffbadc2 Compare November 20, 2026 14:52
@magurotuna
magurotuna marked this pull request as ready for review November 20, 2026 15:05
@MikeMcC399

Copy link
Copy Markdown
Member

The recommendations in:

advise you should tackle only one issue at a time and that you should not open any new PRs until your first PR has been approved.

You already have another unapproved PR #67508 open at this time.

Until the first PR has been approved and has landed in the main branch, GitHub classifies you as "first-time contributor". Each PR commit you push needs to be individually approved by team members to run in GitHub Actions CI. This causes delays for you as a contributor, and it adds to the work load for the team.

Waiting until the first PR has landed ensures that you as a contributor have experienced the complete process from PR submission to successful landing. After this has been completed, any new PRs or new commits to an existing PR are treated to rules for regular Contributors. GitHub Actions CI workflows are then run automatically without intervention by a team member.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants